home *** CD-ROM | disk | FTP | other *** search
/ Chip 2007 January, February, March & April / Chip-Cover-CD-2007-02.iso / Pakiet bezpieczenstwa / mini Pentoo LiveCD 2006.1 / mpentoo-2006.1.iso / livecd.squashfs / usr / lib / mozilla-firefox / idl / nsIMIMEHeaderParam.idl < prev    next >
Text File  |  2006-05-08  |  10KB  |  202 lines
  1. /* -*- Mode: IDL; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
  2. /* vim:expandtab:shiftwidth=4:tabstop=4:
  3.  */
  4. /* ***** BEGIN LICENSE BLOCK *****
  5.  * Version: MPL 1.1/GPL 2.0/LGPL 2.1
  6.  *
  7.  * The contents of this file are subject to the Mozilla Public License Version
  8.  * 1.1 (the "License"); you may not use this file except in compliance with
  9.  * the License. You may obtain a copy of the License at
  10.  * http://www.mozilla.org/MPL/
  11.  *
  12.  * Software distributed under the License is distributed on an "AS IS" basis,
  13.  * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
  14.  * for the specific language governing rights and limitations under the
  15.  * License.
  16.  *
  17.  * The Original Code is mozilla.org code.
  18.  *
  19.  * The Initial Developer of the Original Code is
  20.  * Jungshik Shin <jshin@mailaps.org>
  21.  * Portions created by the Initial Developer are Copyright (C) 2003.
  22.  * the Initial Developer. All Rights Reserved.
  23.  *
  24.  * Contributor(s):
  25.  *
  26.  * Alternatively, the contents of this file may be used under the terms of
  27.  * either the GNU General Public License Version 2 or later (the "GPL"), or
  28.  * the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),
  29.  * in which case the provisions of the GPL or the LGPL are applicable instead
  30.  * of those above. If you wish to allow use of your version of this file only
  31.  * under the terms of either the GPL or the LGPL, and not to allow others to
  32.  * use your version of this file under the terms of the MPL, indicate your
  33.  * decision by deleting the provisions above and replace them with the notice
  34.  * and other provisions required by the GPL or the LGPL. If you do not delete
  35.  * the provisions above, a recipient may use your version of this file under
  36.  * the terms of any one of the MPL, the GPL or the LGPL.
  37.  *
  38.  * ***** END LICENSE BLOCK ***** */
  39.  
  40. /*
  41.  * This interface allows any module to access the routine 
  42.  * for MIME header parameter parsing (RFC 2231)
  43.  */
  44.  
  45. #include "nsISupports.idl"
  46.  
  47. [scriptable, uuid(ddbbdfb8-a1c0-4dd5-a31b-5d2a7a3bb6ec)]
  48. interface nsIMIMEHeaderParam : nsISupports {
  49.  
  50.   /** 
  51.    * Given the value of a single header field  (such as
  52.    * Content-Disposition and Content-Type) and the name of a parameter
  53.    * (e.g. filename, name, charset), returns the value of the parameter.
  54.    * The value is obtained by decoding RFC 2231-style encoding,
  55.    * RFC 2047-style encoding, and converting to UniChar(UTF-16)
  56.    * from charset specified in RFC 2231/2047 encoding, UTF-8, 
  57.    * <code>aFallbackCharset</code> and the locale charset as the last
  58.    * resort if <code>TryLocaleCharset</code> is set.
  59.    *
  60.    * <p> 
  61.    * This method internally invokes <code>getParameterInternal</code>, 
  62.    * However, it does not stop at decoding RFC 2231 (the task for
  63.    * <code>getParameterInternal</code> but tries to cope
  64.    * with several non-standard-compliant cases mentioned below.
  65.    *
  66.    * <p>
  67.    * Note that a lot of MUAs and HTTP servers put RFC 2047-encoded parameters 
  68.    * in mail headers and HTTP headers. Unfortunately, this includes Mozilla 
  69.    * as of 2003-05-30. Even more standard-ignorant MUAs, web servers and 
  70.    * application servers put 'raw 8bit characters'. This will try to cope 
  71.    * with all these cases as gracefully as possible. Additionally, it 
  72.    * returns the language tag if the parameter is encoded per RFC 2231 and 
  73.    * includes lang.
  74.    *
  75.    *
  76.    *
  77.    * @param  aHeaderVal        a header string to get the value of a parameter 
  78.    *                           from.
  79.    * @param  aParamName        the name of a MIME header parameter (e.g. 
  80.    *                           filename, name, charset). If empty,  returns 
  81.    *                           the first (possibly) _unnamed_ 'parameter'.
  82.    * @param  aFallbackCharset  fallback charset to try if  the string after
  83.    *                           RFC 2231/2047 decoding or the raw 8bit 
  84.    *                           string is not UTF-8
  85.    * @param  aTryLocaleCharset If set, makes yet another attempt 
  86.    *                           with the locale charset.
  87.    * @param  aLang             If non-null, assigns it to a pointer 
  88.    *                           to a string containing the value of language 
  89.    *                           obtained from RFC 2231 parsing. Caller has to 
  90.    *                           nsMemory::Free it.
  91.    * @return the value of <code>aParamName</code> in Unichar(UTF-16).
  92.    */
  93.  
  94.   AString getParameter(in ACString aHeaderVal,
  95.                        in string aParamName,
  96.                        in ACString aFallbackCharset,
  97.                        in boolean aTryLocaleCharset, 
  98.                        out string aLang);
  99.   /** 
  100.    * Given the value of a single header field  (such as
  101.    * Content-Disposition and Content-Type) and the name of a parameter
  102.    * (e.g. filename, name, charset), returns the value of the parameter 
  103.    * after decoding RFC 2231-style encoding. 
  104.    * <p>
  105.    * For <strong>internal use only</strong>. The only other place where 
  106.    * this needs to be  invoked  is  |MimeHeaders_get_parameter| in 
  107.    * mailnews/mime/src/mimehdrs.cpp defined as 
  108.    * char * MimeHeaders_get_parameter (const char *header_value, 
  109.    *                                   const char *parm_name,
  110.    *                                   char **charset, char **language)
  111.    *
  112.    * Otherwise, this method would have been made static.
  113.    *
  114.    * @param  aHeaderVal  a header string to get the value of a parameter from.
  115.    * @param  aParamName  the name of a MIME header parameter (e.g. 
  116.    *                     filename, name, charset). If empty,  returns 
  117.    *                     the first (possibly) _unnamed_ 'parameter'.
  118.    * @param  aCharset    If non-null, it gets assigned a new pointer
  119.    *                     to a string containing the value of charset obtained
  120.    *                     from RFC 2231 parsing. Caller has to nsMemory::Free it.
  121.    * @param  aLang       If non-null, it gets assigned a new pointer
  122.    *                     to a string containing the value of language obtained
  123.    *                     from RFC 2231 parsing. Caller has to nsMemory::Free it.
  124.    * @return             the value of <code>aParamName</code> after
  125.    *                     RFC 2231 decoding but without charset conversion.
  126.    */
  127.  
  128.   [noscript]
  129.   string getParameterInternal(in string aHeaderVal,
  130.                               in string aParamName,
  131.                               out string aCharset,
  132.                               out string aLang);
  133.  
  134.  
  135.   /** 
  136.    * Given a header value, decodes RFC 2047-style encoding and
  137.    * returns the decoded header value in UTF-8 if either it's
  138.    * RFC-2047-encoded or aDefaultCharset is given. Otherwise,
  139.    * returns the input header value (in whatever encoding) 
  140.    * as it is except that  RFC 822 (using backslash) quotation and 
  141.    * CRLF (if aEatContinuation is set) are stripped away
  142.    * <p>
  143.    * For internal use only. The only other place where this needs to be 
  144.    * invoked  is  <code>MIME_DecodeMimeHeader</code> in 
  145.    * mailnews/mime/src/mimehdrs.cpp defined as
  146.    * char * Mime_DecodeMimeHeader(char *header_val, const char *charset, 
  147.    *                              PRBool override, PRBool eatcontinuation)
  148.    *
  149.    * @param aHeaderVal       a header value to decode
  150.    * @param aDefaultCharset  MIME charset to use in place of MIME charset
  151.    *                         specified in RFC 2047 style encoding
  152.    *                         when <code>aOverrideCharset</code> is set.
  153.    * @param aOverrideCharset When set, overrides MIME charset specified 
  154.    *                         in RFC 2047 style encoding with <code>aDefaultCharset</code>
  155.    * @param aEatContinuation When set, removes CR/LF
  156.    * @return                 decoded header value
  157.    */
  158.   [noscript]
  159.   ACString decodeRFC2047Header(in string aHeaderVal,
  160.                                in string aDefaultCharset,
  161.                                in boolean aOverrideCharset,
  162.                                in boolean aEatContinuation);
  163.  
  164.  
  165.   /** 
  166.    * Given a header parameter, decodes RFC 2047 style encoding (if it's 
  167.    * not obtained from RFC 2231 encoding),  converts it to
  168.    * UTF-8 and returns the result in UTF-8 if an attempt to extract 
  169.    * charset info. from a few different sources succeeds.
  170.    * Otherwise,  returns the input header value (in whatever encoding) 
  171.    * as it is except that  RFC 822 (using backslash) quotation is
  172.    * stripped off.
  173.    * <p>
  174.    * For internal use only. The only other place where this needs to be 
  175.    * invoked  is  <code>mime_decode_filename</code> in 
  176.    * mailnews/mime/src/mimehdrs.cpp defined as
  177.    * char * mime_decode_filename(char *name, const char *charset, 
  178.    *                             MimeDisplayOptions *opt) 
  179.    *
  180.    * @param aParamValue      the value of a parameter to decode and convert
  181.    * @param aCharset         charset obtained from RFC 2231 decoding  in which 
  182.    *                         <code>aParamValue</code> is encoded. If null,
  183.    *                         indicates that it needs to try RFC 2047, instead. 
  184.    * @param aDefaultCharset  MIME charset to use when aCharset is null and
  185.    *                         cannot be obtained per RFC 2047 (most likely 
  186.    *                         because 'bare' string is  used.)  Besides, it 
  187.    *                         overrides aCharset/MIME charset obtained from 
  188.    *                         RFC 2047 if <code>aOverrideCharset</code>  is set.
  189.    * @param aOverrideCharset When set, overrides MIME charset specified 
  190.    *                         in RFC 2047 style encoding with 
  191.    *                         <code>aDefaultCharset</code>
  192.    * @return                 decoded parameter 
  193.    */
  194.  
  195.   [noscript]
  196.    ACString decodeParameter(in ACString aParamValue,
  197.                             in string aCharset,
  198.                             in string aDefaultCharset,
  199.                             in boolean aOverrideCharset);
  200. };
  201.  
  202.